home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Standards 1994 January / InfoMagic Standards - January 1994.iso / iso / 9660 / rockrdge / rrg.11 / api.lib.nr < prev    next >
Text File  |  1992-08-19  |  11KB  |  612 lines
  1. .sp
  2. .H 2 "Definition of CD-ROM Specific Library Functions for Users"
  3. .sp
  4. This sections provides manual pages which describe CD-ROM library functions
  5. for users in detail.
  6. The library routines are:
  7. .sp
  8. .TS
  9. center;
  10. l l.
  11. Name    Description
  12. \_    \_
  13.           
  14. cd_suf()    Retrieve a System Use Field
  15.           
  16. cd_setdevmap()    Set mappings of major/minor numbers
  17.           
  18. cd_getdevmap()    Get mappings of major/minor numbers
  19. .TE
  20. .sp
  21. .bp
  22. .sp
  23. .H 3 "cd_suf library routine"
  24. .sp
  25. .in 0
  26. .ft 3
  27. NAME
  28. .ft 1
  29. .br
  30. .in 2
  31. .ft 3
  32. cd_suf 
  33. .ft 1
  34. - read System Use Field from a specified System Use Area
  35. .sp
  36. .in 0
  37. .ft 3
  38. SYNOPSIS
  39. .ft 1
  40. .in 2
  41. .ft 3
  42. .br
  43. #include <sys/cdrom.h>
  44. .sp
  45. int cd_suf (path, fsec, signature, index, buf, buflen)
  46. .br
  47. char    *path;
  48. .br
  49. int    fsec;
  50. .br
  51. char    signature[2];
  52. .br
  53. int    index;
  54. .br
  55. char    *buf;
  56. .br
  57. int    buflen;
  58. .sp
  59. .ft 1
  60. .in 0
  61. .ft 3
  62. DESCRIPTION
  63. .ft 1
  64. .in 2
  65. .br
  66. .I Cd_suf\^
  67. returns a System Use Field in the System Use Area for
  68. .I path.\^
  69. .sp
  70. .I Path\^
  71. points to a file or directory within the CD-ROM file hierarchy.
  72. .sp
  73. .I Fsec\^
  74. specifies the File Section of that file. 
  75. The numbering starts with one.
  76. If
  77. .I fsec\^
  78. is set to -1, the System Use Area of the last File Section of that file
  79. is assumed.
  80. .sp
  81. .I Signature\^
  82. is the 2 byte signature to look for and return from the System Use Area.
  83. .sp
  84. .I Index\^
  85. is the occurrence of
  86. .I signature\^ 
  87. to return.
  88. If
  89. .I signature\^
  90. is a NULL pointer, return the
  91. .I index\^
  92. System Use Field starting from the beginning of the System Use Area.
  93. Otherwise, return the
  94. .I index\^
  95. occurrence of
  96. .I signature.\^
  97. The
  98. .I index\^
  99. number of the first System Use Field of any
  100. .I signature\^
  101. is one.
  102. .sp
  103. .I Buf\^
  104. and
  105. .I buflen\^
  106. are the buffer and buffer length in which to place the System Use Field.
  107. .sp
  108. .in 0
  109. .ft 3
  110. RETURN VALUE
  111. .ft 1
  112. .in 2
  113. .br
  114. .I Cd_suf\^
  115. will return the number of bytes placed in
  116. .I buf\^
  117. if successful.
  118. .I Cd_suf\^
  119. will return 0 if the
  120. .I signature\^
  121. field is not found.
  122. In case of error, -1 is returned and
  123. .I errno\^
  124. is set to indicate the error.
  125. .sp
  126. .in 0
  127. .ft 3
  128. ERRORS
  129. .ft 1
  130. .in 2
  131. .br
  132. The 
  133. .I cd_suf()\^
  134. function will fail if:
  135. .sp
  136. .VL 15
  137. .LI "[EACCESS]"
  138. Search permission is denied for a component of the
  139. .I path\^
  140. prefix or read permission on the file or directory pointed to by
  141. .I path\^
  142. is denied.
  143. .LI "[ENAMETOOLONG]"
  144. The length of the
  145. .I path\^
  146. string exceeds {PATH_MAX} or a pathname component is longer than
  147. {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
  148. .LI "[ENOENT]"
  149. A component of
  150. .I path\^
  151. does not exist or the
  152. .I path\^
  153. argument points to an empty string.
  154. .br
  155. The File Section indicated by 
  156. .I fsec\^
  157. has no System Use Area.
  158. .LI "[ENOTDIR]"
  159. A component of the
  160. .I path\^
  161. prefix is not a directory.
  162. .LI "[EFAULT]"
  163. The address of
  164. .I buf,\^
  165. .I signature\^
  166. or
  167. .I path\^
  168. is invalid.
  169. .LI "[EINVAL]"
  170. The value of
  171. .I fsec,\^
  172. .I index\^
  173. or
  174. .I buflen\^
  175. is invalid.
  176. .br
  177. The argument
  178. .I path\^
  179. points to a file/directory not within a CD-ROM file hierarchy.
  180. .LI "[ENODEV]"
  181. The Volume containing the File Section indicated by
  182. .I fsec\^
  183. is not mounted.
  184. .LI "[ENXIO]"
  185. The CD-ROM is not in the drive or a read error occurred.
  186. .LI "[EINTR]"
  187. A signal was caught during the 
  188. .I cd_suf()\^
  189. function.
  190. .LI "[EMFILE]"
  191. {OPEN_MAX} file descriptors are currently open in the calling process.
  192. .LI "[ENFILE]"
  193. The system file table is full.
  194. .LE
  195. .sp
  196. .in 0
  197. .ft 3
  198. SEE ALSO
  199. .ft 1
  200. .in 2
  201. .br
  202. <sys/cdrom.h>
  203. .sp
  204. .in 0
  205. .bp
  206. .sp
  207. .H 3 "cd_setdevmap library routine"
  208. .sp
  209. .in 0
  210. .ft 3
  211. NAME
  212. .ft 1
  213. .in 2
  214. .br
  215. .ft 3
  216. cd_setdevmap 
  217. .ft 1
  218. - set mappings of major/minor numbers
  219. .sp
  220. .in 0
  221. .ft 3
  222. SYNOPSIS
  223. .ft 1
  224. .in 2
  225. .ft 3
  226. .br
  227. #include <sys/cdrom.h>
  228. .sp
  229. int cd_setdevmap (path, cmd, new_major, new_minor)
  230. .br
  231. char    *path;
  232. .br
  233. int    cmd;
  234. .br
  235. int    *new_major;
  236. .br
  237. int    *new_minor;
  238. .sp
  239. .ft 1
  240. .in 0
  241. .ft 3
  242. DESCRIPTION
  243. .ft 1
  244. .in 2
  245. .br
  246. This function sets or unsets (based on
  247. .I cmd\^)
  248. the major and minor numbers of one device file on a mounted CD-ROM.
  249. The argument
  250. .I path\^
  251. points to a file or directory within the CD-ROM file hierarchy.
  252. .sp
  253. If 
  254. .I cmd\^
  255. is CD_SETDMAP, this function maps the
  256. .I new_major
  257. major number and the
  258. .I new_minor
  259. minor number to the device file pointed to by
  260. .I path.
  261. .I New_major\^
  262. specifies the new major number for the device file.
  263. .I New_minor\^
  264. specifies the new minor number for the device file.
  265. Any device file mapping for the device file
  266. .I path\^
  267. set with a previous invocation of
  268. .I cd_setdevmap()\^
  269. is overridden by this invocation of
  270. .I cd_setdevmap().\^
  271. .sp
  272. If 
  273. .I cmd\^
  274. is CD_UNSETDMAP, this function unmaps the mapped major and 
  275. minor numbers of the device file pointed to by
  276. .I path.\^
  277. The value of the recorded major number on the CD-ROM shall be returned in
  278. .I new_major.\^
  279. The value of the recorded minor number on the CD-ROM shall be returned in
  280. .I new_minor.\^
  281. .sp
  282. See 
  283. .ft 3
  284. Section 1.1, Mapping Device Files 
  285. .ft 1
  286. for further information.
  287. .sp
  288. .in 0
  289. .ft 3
  290. RETURN VALUE
  291. .ft 1
  292. .in 2
  293. .br
  294. For CD_SETDMAP,
  295. .I cd_setdevmap\^
  296. will return one if the device file is successfully mapped 
  297. (a return value of zero means no more mappings allowed).
  298. .sp
  299. For CD_UNSETDMAP,
  300. .I cd_setdevmap\^
  301. will return one if the device file is successfully unmapped 
  302. (a return value of zero means mapping not found).
  303. .sp
  304. In case of error, -1 is returned and
  305. .I errno\^
  306. is set to indicate the error.
  307. .sp
  308. .in 0
  309. .ft 3
  310. ERRORS
  311. .ft 1
  312. .in 2
  313. .br
  314. .VL 15
  315. .LI "[EACCESS]"
  316. Search permission is denied for a component of the
  317. .I path\^
  318. prefix or read permission on the device file pointed to by
  319. .I path\^
  320. is denied.
  321. .LI "[ENAMETOOLONG]"
  322. The length of the
  323. .I path\^
  324. string exceeds {PATH_MAX} or a pathname component is longer than
  325. {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
  326. .LI "[ENOENT]"
  327. A component of
  328. .I path\^
  329. does not exist or the
  330. .I path\^
  331. argument points to an empty string.
  332. .LI "[ENOTDIR]"
  333. A component of the
  334. .I path\^
  335. prefix is not a directory.
  336. .LI "[EFAULT]"
  337. The address of
  338. .I path,\^
  339. .I new_major,\^
  340. or
  341. .I new_minor\^
  342. is invalid.
  343. .LI "[EINVAL]"
  344. The value of
  345. .I cmd\^
  346. is invalid.
  347. .br
  348. The argument
  349. .I path\^
  350. points to a file/directory not within a CD-ROM file hierarchy.
  351. .br
  352. The file pointed to by
  353. .I path\^
  354. is not a device file.
  355. .LI "[EPERM]"
  356. User does not have appropriate privileges to set/unset device file
  357. major/minor values.
  358. .LI "[ENXIO]"
  359. The CD-ROM is not in the drive or a read error occurred.
  360. .LI "[EINTR]"
  361. A signal was caught during the 
  362. .I cd_setdevmap()\^
  363. function.
  364. .LI "[EMFILE]"
  365. {OPEN_MAX} file descriptors are currently open in the calling process.
  366. .LI "[ENFILE]"
  367. The system file table is full.
  368. .LE
  369. .sp
  370. .in 0
  371. .ft 3
  372. APPLICATION USAGE
  373. .ft 1
  374. .in 2
  375. .br
  376. The use of
  377. .I cd_setdevmap()\^
  378. is restricted to a user with appropriate privileges.
  379. The maximum number of mappings is defined in
  380. .I <sys/cdrom.h>.\^
  381. Mappings should be established before affected device files are used.
  382. If this function is applied for device files that have already been opened,
  383. the effect of this function on these files is undefined. 
  384. The device file mappings for a mounted CD-ROM are eliminated when the 
  385. CD-ROM is unmounted.
  386. .sp
  387. .in 0
  388. .ft 3
  389. SEE ALSO
  390. .ft 1
  391. .in 2
  392. .br
  393. <sys/cdrom.h>
  394. .sp
  395. .in 0
  396. .bp
  397. .sp
  398. .H 3 "cd_getdevmap library routine"
  399. .sp
  400. .in 0
  401. .ft 3
  402. NAME
  403. .ft 1
  404. .in 2
  405. .br
  406. .ft 3
  407. cd_getdevmap 
  408. .ft 1
  409. - get mappings of major/minor numbers
  410. .sp
  411. .in 0
  412. .ft 3
  413. SYNOPSIS
  414. .ft 1
  415. .in 2
  416. .ft 3
  417. .br
  418. #include <sys/cdrom.h>
  419. .sp
  420. int cd_getdevmap (path, pathlen, index, new_major, new_minor)
  421. .br
  422. char    *path;
  423. .br
  424. int    pathlen;
  425. .br
  426. int    index;
  427. .br
  428. int    *new_major;
  429. .br
  430. int    *new_minor;
  431. .sp
  432. .ft 1
  433. .in 0
  434. .ft 3
  435. DESCRIPTION
  436. .ft 1
  437. .in 2
  438. .br
  439. This function gets
  440. the major and minor numbers of one device file on a mounted CD-ROM.
  441. The argument
  442. .I path\^
  443. points to a file or directory within the CD-ROM file hierarchy.
  444. The argument
  445. .I index\^
  446. refers to the \f2index\f1'th mapped device file.
  447. Mappings can be obtained by
  448. .I path\^
  449. or 
  450. .I index.\^
  451. .sp
  452. If 
  453. .I index\^
  454. is zero, this function gets the mapped major and minor numbers
  455. of the device file pointed to by
  456. .I path.\^
  457. The value of the mapped major number shall be returned in
  458. .I new_major.\^
  459. The value of the mapped minor number shall be returned in
  460. .I new_minor.\^
  461. The value of
  462. .I pathlen\^
  463. is not used.
  464. .sp
  465. If 
  466. .I index\^
  467. is not zero, this function gets the major and minor numbers
  468. and pathname of the \f2index\f1'th mapped device file.
  469. Numbering for
  470. .I index\^
  471. starts at one.
  472. The value of the mapped major number shall be returned in
  473. .I new_major.\^
  474. The value of the mapped minor number shall be returned in
  475. .I new_minor.\^
  476. The pathname of the device file shall be returned in
  477. .I path.\^
  478. If the length of the pathname for the device file is longer than
  479. .I pathlen\^
  480. the pathname returned in
  481. .I path\^
  482. will be truncated to
  483. .I pathlen\^
  484. length and will not be NULL terminated.
  485. .sp
  486. See 
  487. .ft 3
  488. Section 1.1, Mapping Device Files 
  489. .ft 1
  490. for further information.
  491. .sp
  492. .in 0
  493. .ft 3
  494. RETURN VALUE
  495. .ft 1
  496. .in 2
  497. .br
  498. .I cd_getdevmap\^
  499. will return the length of pathname if the device file is 
  500. successfully returned
  501. (a return value of zero means mapping not found).
  502. Note: if the pathname is truncated, the return value will be
  503. larger than
  504. .I pathlen.\^
  505. .sp
  506. In case of error, -1 is returned and
  507. .I errno\^
  508. is set to indicate the error.
  509. .sp
  510. .in 0
  511. .ft 3
  512. ERRORS
  513. .ft 1
  514. .in 2
  515. .br
  516. .VL 15
  517. .LI "[EACCESS]"
  518. Search permission is denied for a component of the
  519. .I path\^
  520. prefix or read permission on the device file pointed to by
  521. .I path\^
  522. is denied.
  523. .LI "[ENAMETOOLONG]"
  524. The length of the
  525. .I path\^
  526. string exceeds {PATH_MAX} or a pathname component is longer than
  527. {NAME_MAX} while {_POSIX_NO_TRUNC} is in effect.
  528. .LI "[ENOENT]"
  529. A component of
  530. .I path\^
  531. does not exist or the
  532. .I path\^
  533. argument points to an empty string.
  534. .LI "[ENOTDIR]"
  535. A component of the
  536. .I path\^
  537. prefix is not a directory.
  538. .LI "[EFAULT]"
  539. The address of
  540. .I path,\^
  541. .I new_major,\^
  542. or
  543. .I new_minor\^
  544. is invalid.
  545. .LI "[EINVAL]"
  546. The value of
  547. .I index\^
  548. or
  549. .I pathlen\^
  550. is invalid.
  551. .br
  552. The argument
  553. .I path\^
  554. points to a file/directory not within a CD-ROM file hierarchy.
  555. .br
  556. The file pointed to by
  557. .I path\^
  558. is not a device file.
  559. .LI "[ENXIO]"
  560. The CD-ROM is not in the drive or a read error occurred.
  561. .LI "[EINTR]"
  562. A signal was caught during the 
  563. .I cd_getdevmap()\^
  564. function.
  565. .LI "[EMFILE]"
  566. {OPEN_MAX} file descriptors are currently open in the calling process.
  567. .LI "[ENFILE]"
  568. The system file table is full.
  569. .LE
  570. .sp
  571. .in 0
  572. .ft 3
  573. APPLICATION USAGE
  574. .ft 1
  575. .in 2
  576. .br
  577. The maximum number of mappings is defined in
  578. .I <sys/cdrom.h>.\^
  579. The device file mappings for a mounted CD-ROM are undone when the 
  580. CD-ROM is unmounted.
  581. .sp
  582. The
  583. .I index\^
  584. numbers from 1 to
  585. .I n\^
  586. (where
  587. .I n\^
  588. is the number of the last device file mapping)
  589. are always guaranteed to have a device file mapping associated
  590. with the number.
  591. Thus if an application wishes to successively delete all
  592. device file mappings, one at a time, it would call 
  593. .I cd_getdevmap()\^
  594. with
  595. .I index\^
  596. equal to 1, and then
  597. .I cd_setdevmap()\^
  598. with CD_UNSETDMAP in a loop until 
  599. .I cd_getdevmap()\^
  600. returns zero.
  601. .sp
  602. .in 0
  603. .ft 3
  604. SEE ALSO
  605. .ft 1
  606. .in 2
  607. .br
  608. <sys/cdrom.h>
  609. .sp
  610. .in 0
  611. .bp
  612.